---
layout: docs
page_title: Nomad volume specification `topology_request` block
description: |-
  Configure Container Storage Interface (CSI) storage volume topology in the `topology_request` block of the Nomad volume specification. Specify region, zone, and rack so that Nomad can access a provisioned CSI volume. Review volume creation examples with preferred and required topologies.
---

# Nomad volume specification `topology_request` block

<Placement
  groups={[
    ['volume', 'topology_request'],
  ]}
/>

Specify locations such as region, zone, and rack, where a provisioned CSI volume must
be accessible, or where an existing volume is accessible. The `topology_request`
block is not supported for dynamic host volumes.


```hcl
id           = "ebs_prod_db1"
namespace    = "default"
name         = "database"
type         = "csi"
plugin_id    = "ebs-prod"
capacity_max = "200G"
capacity_min = "100G"

topology_request {
  required {
    topology { segments { rack = "R2" } }
    topology { segments { rack = "R1", zone = "us-east-1a"} }
  }
  preferred {
    topology { segments { rack = "R1", zone = "us-east-1a"} }
  }
}
```

Consult the documentation for your storage provider and CSI plugin as to
whether it supports defining topology and what values it expects for topology
segments. Specifying topology segments that aren't supported by the storage
provider may return an error or may be silently removed by the plugin.

## Parameters

- `required` <code>([Topology][topology]: nil)</code> - On **volume creation**,
  the `required` topologies indicate that the volume must be created in a
  location accessible from at least one of the listed topologies. On **volume
  registration** the `required` topologies indicate that the volume was created
  in a location accessible from all the listed topologies.

- `preferred` <code>([Topology][topology]: nil)</code> - Indicate that you
  would prefer the storage provider to create the volume in one of the provided
  topologies. Only allowed on **volume creation**.

### `topology` parameters

- `segments` `(map[string]string)` - A map of location types to their values.
  The specific fields required are defined by the CSI plugin.

## Example

This example illustrates volume creation with `preferred` and `required`
topologies. The configuration requires Nomad to create the volume within racks
`R1` or `R2`, but that you prefer creation within `R1`.

```hcl
topology_request {
  required {
    topology { segments { rack = "R1", zone = "us-east-1a" } }
    topology { segments { rack = "R2", zone = "us-east-1a" } }
  }
  preferred {
    topology { segments { rack = "R1", zone = "us-east-1a"} }
  }
}
```

[topology]: #topology-parameters
